Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

NS_DEV_DOCFOR:objc_class:Font;,Font

Inherits From:	Object

Declared In:	appkit/Font.h

Class Description

The Font class provides objects that correspond to PostScript fonts.  Each Font object records a font's name, size, style, and matrix.  When a Font object receives a set message, it establishes its font as the current font in the Window Server's current graphics state.

For a given application, only one Font object is created for a particular PostScript font.  When the Font class object receives a message to create a new object for a particular font, it first checks whether one has already been created for that font.  If so, it returns existing object; otherwise, it creates a new object and returns it.  To implement this sharing of Font objects, the Font class provides special instantiation methods (the new... methods, userFixedPitchFontOfSize:matrix:, and so on); use these methods, not alloc or allocFromZone:.

This sharing Font objects minimizes the number of objects created.  It also implies that no one object in your application can know whether it has the only reference to a particular Font object.  Thus, Font objects shouldn't be freed; Font's free method simply returns self.

Instance Variables

char *name;

float size;

int style;

float *matrix;

int fontNum;

NXFaceInfo *faceInfo;

id otherFont;

struct _fFlags {
	unsigned int  isScreenFont:1;

} fFlags;

name 	The font's name.

size 	The font's size.

style 	The font's style.

matrix 	The font's matrix.

fontNum 	The user object referring to this font.

faceInfo 	The font's face information.

otherFont 	The associated screen font for this font.

fFlags.isScreenFont 	True if the font is a screen font.

Method Types

Initializing the Class object	+ initialize
+ useFont:

Creating and freeing a Font object
+ newFont:size:
+ newFont:size:matrix:
+ newFont:size:style:matrix:
+ boldSystemFontOfSize:matrix:
+ userFixedPitchFontOfSize:matrix:
+ userFontOfSize:matrix:
+ systemFontOfSize:matrix:
- free

Querying the Font object	- displayName
- familyName
- name
- fontNum
- getWidthOf:
- hasMatrix
- matrix
- metrics
- pointSize
- readMetrics:
- screenFont
- style

Setting the font	- set
- setStyle:
+ setUserFixedPitchFont:
+ setUserFont:

Archiving	- awake
- finishUnarchiving
- read:
- write:

Class Methods

NS_DEV_DOCFOR:objc_method:[Font-allocFromZone:];,allocFromZone:

+ allocFromZone:(NXZone *)zone

Creates an uninitialized Font object in the specified zone.  Don't use this method to create a Font; instead, use newFont:size: or one of the other Font creation methods listed in ªMethod Typesº above.

See also:  + newFont:size:style:matrix:, + newFont:size:matrix:, + newFont:size:

NS_DEV_DOCFOR:objc_method:[Font-boldSystemFontOfSize:matrix:];,boldSystemFontOfSize:matrix:

+ boldSystemFontOfSize:(float)fontSize matrix:(const float *)fontMatrix

Returns the Font object representing the bold system font of size fontSize and matrix fontMatrix.  The bold system font is used for text in attention panels, window titles, and so on.  If fontSize is 0, the size as recorded in the Preferences application's General Preferences display is used.  fontMatrix can be NX_IDENTITYMATRIX or NX_FLIPPEDMATRIX.  (See newFont:size:style:matrix: for more information on font matrices.)

This method raises the NX_unavailableFont exception if a suitable Font object can't be found.

See also:  + systemFontOfSize:matrix:, + userFixedPitchFontOfSize:matrix:, + userFontOfSize:matrix:

NS_DEV_DOCFOR:objc_method:[Font-initialize];,initialize

+ initialize

Initializes the Font class object.  The class object receives an initialize message before it receives any other message.  You never send an initialize message directly.

See also:  + initialize (Object)

NS_DEV_DOCFOR:objc_method:[Font-newFont:size:];,newFont:size:

+ newFont:(const char *)fontName size:(float)fontSize

Returns a Font object for font fontName of size fontSize.  This method invokes the newFont:size:style:matrix: method with the style set to 0 and the matrix set to NX_FLIPPEDMATRIX.

See also:  + newFont:size:style:matrix:, + newFont:size:matrix:

NS_DEV_DOCFOR:objc_method:[Font-newFont:size:matrix:];,newFont:size:matrix:

+ newFont:(const char *)fontName
size:(float)fontSize
matrix:(const float *)fontMatrix

Returns a Font object for font fontName of size fontSize.  This method invokes the newFont:size:style:matrix: method with the style set to 0.

See also:  + newFont:size:style:matrix:, + newFont:size:

NS_DEV_DOCFOR:objc_method:[Font-newFont:size:style:matrix:];,newFont:size:style:matrix:

+ newFont:(const char *)fontName
size:(float)fontSize
style:(int)fontStyle
matrix:(const float *)fontMatrix

Returns a Font object for font fontName, of size fontSize, and matrix fontMatrix.  fontStyle is currently ignored.  If an appropriate Font object was previously created, it's returned; otherwise, a new one is created and returned.  If an error occurs, this method returns nil.  This is the designated new... method for the Font class.  

There are two constants available for the fontMatrix parameter:

·	NX_IDENTITYMATRIX.  Use the identity matrix.

·	NX_FLIPPEDMATRIX.  Use a flipped matrix.  (Appropriate for a flipped View like the Text object.)

The fontStyle parameter is stored in the Font object, and is preserved by the FontManager's convertFont: method, but is not used by the Application Kit.  It can be used to store application-specific font information.

Note:  If this method is invoked from a subclass (through a message to super), a new object is always created.  Thus, your subclass should institute its own system for sharing Font objects.

See also:  + newFont:size:matrix:, + newFont:size:

NS_DEV_DOCFOR:objc_method:[Font-setUserFixedPitchFont:];,setUserFixedPitchFont:

+ setUserFixedPitchFont:(Font *)aFont

Sets the fixed-pitch font that's used by default in the application.  This method is intended for an application that wants to override the default fixed-pitch font as recorded in the Preferences application's General Preferences display.

See also:  + userFixedPitchFontOfSize:matrix:, + setUserFont:

NS_DEV_DOCFOR:objc_method:[Font-setUserFont:];,setUserFont:

+ setUserFont:(Font *)aFont

Sets the standard font that's used by default in the application.  This method is intended for an application that wants to override the default standard font as recorded in the Preferences application's General Preferences display.

See also:  + userFontOfSize:matrix:, + setUserFixedPitchFont:

NS_DEV_DOCFOR:objc_method:[Font-systemFontOfSize:matrix:];,systemFontOfSize:matrix:

+ systemFontOfSize:(float)fontSize matrix:(const float *)fontMatrix

Returns the Font object representing the system font of size fontSize and matrix fontMatrix.  The system font is used for text in attention panels, menus, and so on.  If fontSize is 0, the size as recorded in the Preferences application's General Preferences display is used.  fontMatrix can be NX_IDENTITYMATRIX or NX_FLIPPEDMATRIX.  (See newFont:size:style:matrix: for more information on font matrices.)

This method raises the NX_unavailableFont exception if a suitable Font object can't be found.

See also:  + boldSystemFontOfSize:matrix:, + userFixedPitchFontOfSize:matrix:, + userFontOfSize:matrix:

NS_DEV_DOCFOR:objc_method:[Font-useFont:];,useFont:

+ useFont:(const char *)fontName

Registers that the font identified by fontName is used in the document.  Returns self.

The Font class object keeps track of the fonts that are being used in a document.  It does this by registering the font whenever a Font object receives a set message.  When a document is called upon to generate a conforming PostScript language version of its text (such as during printing), the Font class provides the list of fonts required for the %%DocumentFonts comment.  (See Document Structuring Conventions by Adobe Systems Inc.)

The useFont: method augments this system by providing a way to register fonts that are included in the document but not set using Font's set method.  For example, you might set a font by executing the setfont operator within a function created by pswrap.  In such a case, make sure to pair the use of the font with a useFont: message to register the font with the Font class object.

See also:  - set

NS_DEV_DOCFOR:objc_method:[Font-userFixedPitchFontOfSize:matrix:];,userFixedPitchFontOfSize:matrix:

+ userFixedPitchFontOfSize:(float)fontSize matrix:(const float *)fontMatrix

Returns the Font object representing the application's fixed-pitch font of size fontSize and matrix fontMatrix.  If fontSize is 0, the size as recorded in the Preferences application's General Preferences display is used.  fontMatrix can be NX_IDENTITYMATRIX or NX_FLIPPEDMATRIX.  (See newFont:size:style:matrix: for more information on font matrices.)

This method raises the NX_unavailableFont exception if a suitable Font object can't be found.

See also:  + setUserFixedPitchFont:, + boldSystemFontOfSize:matrix:, + systemFontOfSize:matrix:, + userFontOfSize:matrix:

NS_DEV_DOCFOR:objc_method:[Font-userFontOfSize:matrix:];,userFontOfSize:matrix:

+ userFontOfSize:(float)fontSize matrix:(const float *)fontMatrix

Returns the Font object representing the application's standard font of size fontSize and matrix fontMatrix.  If fontSize is 0, the size as recorded in the Preferences application's General Preferences display is used.  fontMatrix can be NX_IDENTITYMATRIX or NX_FLIPPEDMATRIX.  (See newFont:size:style:matrix: for more information on font matrices.)

This method provides an easy way to determine the user's font preference, which you can use to initialize new documents.

userFontOfSize:matrix: raises the NX_unavailableFont exception if a suitable Font object can't be found.

See also:  + setUserFixedPitchFont:, + boldSystemFontOfSize:matrix:, + systemFontOfSize:matrix:, + userFixedPitchFontOfSize:matrix:

Instance Methods

NS_DEV_DOCFOR:objc_method:[Font-awake];,awake

- awake

Reinitializes the Font object after it's been read in from a stream.

An awake message is automatically sent to each object of an application after all objects of that application have been read in.  You never send awake messages directly.  The awake message gives the object a chance to complete any initialization that read: couldn't do.  If you override this method in a subclass, the subclass should send this message to its superclass:

[super awake];

Returns self.

See also:  - read:, - write:, - finishUnarchiving

NS_DEV_DOCFOR:objc_method:[Font-displayName];,displayName

- (const char *)displayName

Returns the full name of the font.  For example, the font named ªFutura-CondExtraBoldOblº returns the display name ªFutura Condensed Extra Bold Obliqueº.

See also:  - familyName, - name

NS_DEV_DOCFOR:objc_method:[Font-familyName];,familyName

- (const char *)familyName

Returns the name of the font's family.  For example, the font named ªFutura-CondExtraBoldOblº returns the family name ªFuturaº.

See also:  - displayName, - name

NS_DEV_DOCFOR:objc_method:[Font-finishUnarchiving];,finishUnarchiving

- finishUnarchiving

A finishUnarchiving message is sent after the Font object has been read in from a stream.  This method checks if a Font object for the particular PostScript font already exists.  If so, self is freed and the existing object is returned.

See also:  - read:, - write:, - awake

NS_DEV_DOCFOR:objc_method:[Font-fontNum];,fontNum

- (int)fontNum

Returns the PostScript user object that corresponds to this font.  The Font object must set the font in the Window Server before this method will return a valid user object.  Sending a Font object the set message sets the font in the Window Server.  The fontNum method returns 0 if the Font object hasn't previously received a set message or if the font couldn't be set.

See also:  - set, DPSDefineUserObject()

NS_DEV_DOCFOR:objc_method:[Font-free];,free

- free

Has no effect.  Since only one Font object is allocated for a particular font, and since you can't be sure that you have the only reference to a particular Font object, a Font object shouldn't be freed.

NS_DEV_DOCFOR:objc_method:[Font-getWidthOf:];,getWidthOf:

- (float)getWidthOf:(const char *)string

Returns the width of string using this font.  This method has better performance than the Window Server routine PSstringwidth().

NS_DEV_DOCFOR:objc_method:[Font-hasMatrix];,hasMatrix

- (BOOL)hasMatrix

Returns YES if the Font object's matrix is different from the identity matrix, NX_IDENTITYMATRIX; otherwise, returns NO.

See also:  + newFont:size:style:matrix:, - matrix

NS_DEV_DOCFOR:objc_method:[Font-matrix];,matrix

- (const float *)matrix

Returns a pointer to the matrix for this font.

See also:  - hasMatrix

NS_DEV_DOCFOR:objc_method:[Font-metrics];,metrics

- (NXFontMetrics *)metrics

Returns a pointer to the NXFontMetrics record for the font.  See the header file appkit/afm.h for the structure of an NXFontMetrics record.

See also:  - readMetrics:

NS_DEV_DOCFOR:objc_method:[Font-name];,name

- (const char *)name

Returns the font's name, as would be used in a PostScript language program.

See also:  - displayName, - familyName

NS_DEV_DOCFOR:objc_method:[Font-pointSize];,pointSize

- (float)pointSize

Returns the size of the font in points.

NS_DEV_DOCFOR:objc_method:[Font-read:];,read:

- read:(NXTypedStream *)stream

Reads the Font object's instance variables from stream.  A read: message is sent in response to archiving; you never send this message.

See also:  - write:, - read: (Object)

NS_DEV_DOCFOR:objc_method:[Font-readMetrics:];,readMetrics:

- (NXFontMetrics *)readMetrics:(int)flags

Returns a pointer to the NXFontMetrics record for this font.  The flags argument determines which fields of the record will be filled in.  flags is built by ORing together constants such as NX_FONTHEADER, NX_FONTMETRICS, and NX_FONTWIDTHS.  See the header file appkit/afm.h for the complete list of constants and for the structure of the NXFontMetrics record.

See also:  - metrics

NS_DEV_DOCFOR:objc_method:[Font-screenFont];,screenFont

- screenFont

Provides the screen font corresponding to this font.  If the receiver represents a printer font, this method returns the Font object for the associated screen font (or nil if one doesn't exist).  If the receiver represents a screen font, it simply returns self.

NS_DEV_DOCFOR:objc_method:[Font-set];,set

- set

Makes this font the current font in the current graphics state.  Returns self.  

When a Font object receives a set message, it registers with the Font class object that its PostScript font has been used.  In this way, the Application Kit, when called upon to generate a conforming PostScript language document file, can list the fonts used within a document.  (See Document Structuring Conventions by Adobe Systems Inc.)  If the application uses fonts without sending set messages (say through including an EPS file), such fonts must be registered by sending the class object a useFont: message.

See also:  + useFont:

NS_DEV_DOCFOR:objc_method:[Font-setStyle:];,setStyle:

- setStyle:(int)aStyle

Sets the Font's style.  Setting a style isn't recommended but is minimally supportedÐa Font object's style isn't interpreted in any way by the Application Kit.  You can use it for your own non-PostScript language font styles (a drop-shadow style, for example).  

Be very careful using this method since it causes the Font to stop being shared.  You must reassign the pointer to the Font to the return value of setStyle:.  

font = [font setStyle:12];

Returns self.  

See also:  - style

NS_DEV_DOCFOR:objc_method:[Font-style];,style

- (int)style

Returns the style of the font.  For Font objects created by the Application Kit, this method returns 0.

See also:  - setStyle:

NS_DEV_DOCFOR:objc_method:[Font-write:];,write:

- write:(NXTypedStream *)stream

Writes the Font object's instance variables to stream.  A write: message is sent in response to archiving; you never send this message directly.

See also:  - read:, - write: (Object)